# Design review Oct 1, 2026 · `/plan-design-review`, condensed **Target:** `design/README.md` and the six drawn screens in `design/screens/`. They are compared with the eight pages the thin build renders (`runs/demo/site/`, from `platform_zone/web/`) and with the demo storyline in PRD §6. **How it ran.** The owner declined the interactive question flow, so every fix below is a recommendation and stays **pending** until accepted. Mockups were not generated: the designer tool needs an OpenAI key that is not configured here. The drawn screens and the built pages serve as the visual evidence. Contrast ratios were computed from the tokens. ## System audit - **UI scope:** eight demo screens, plus four that are not yet drawn (brief, low-confidence field review, export approval, de-identification review). - **DESIGN.md:** none. The tokens live in `design/README.md`, and the components live in code (`platform_zone/web/components.py`). - **Prior design reviews:** none. - **Mode:** OPERATE (app UI), shown live to an audience. That second fact drives several findings below. ## Step 0 **Initial rating: 5/10.** The drawn screens are specific: real copy, real numbers, two typefaces with a job each, a calm palette, and source marks that do not rely on colour. What is missing: - states other than the happy path - any home for the screens that must live in the hospital zone - a plan for how this reads on a projector - the four screens not yet drawn A 10 here means: - every screen has its loading, empty, error and partial states - the navigation follows the five acts of the demo - hospital-zone screens are served by the hospital zone - every number on every screen carries its mark and interval - a presentation mode is readable at the back of a meeting room **Existing design to reuse.** The tokens in `design/README.md`, plus the components already built in `components.py`: | Component | Purpose | |---|---| | `label_mark` | Source mark: filled circle, half circle or ring, always with the word | | `quantity` | Value, interval and mark, rendered together | | `SAMPLE_BANNER` | Banner on every page of a synthetic run | | `page` | Rail navigation and the zone indicator | Contrast is already sound: | Text | Background | Ratio | |---|---|---| | Secondary text | Surface | 6.4:1 | | Rail muted text | Rail | 7.7:1 | | Warning text | Warning tint | 5.2:1 | | Accent | Surface | 7.3:1 | ## Pass 1. Information architecture: 5/10 ``` drawn rail (6 steps) demo storyline (5 acts, 13 steps) built rail (8 flat items) 1 Study package 1 Ingest intake, study record Study package 2 Design retrospective 2 Understand retrospective, digest Design retrospective 3 Feedback digest 3 Learn profile, review Feedback digest 4 Behaviour profile 4 Apply brief, simulate, Behaviour profile 5 Simulate forecast, report Simulate twice 6 Design report 5 Trust replay, limits, sign-off Design report Replay and limits Audit and export ``` | # | Finding | Recommended fix | State | |---|---|---|---| | 1 | The rail matches neither the storyline nor itself: six steps drawn, eight built, five acts in the PRD. A presenter walking the acts loses their place. | Group the rail by the five acts, with the steps nested. Audit and export move to a footer link, since they are governance, not story. | **done in sprint 1** | | 2 | Two screens belong in the hospital zone: de-identification review, and export approval by the data steward. The rail shows one app, but the platform web app cannot serve them (hard rule 1, engineering finding A4). | Give the hospital zone its own minimal UI with two screens and the same tokens. The platform rail shows "Hospital zone connected" and the last approved export as a status, not as links. | done in sprint 2: `hospital_zone/console.py`, port 8820 | | 3 | The simulate screen's punchline is buried. The drawn screen leads with a "What changes" column ("7 months longer", "6 points lower"). The built page shows scenarios as rows with no change column. | Rebuild the built page on the drawn layout: one table with outcomes as rows, columns for global, local and what changes, and the change in large mono type. | pending | | 4 | The built package page opens with a file table. The drawn page opens with the drop zone and the "What this study can teach" panel (layers covered), which is the point of act 1. | Lead with the checklist summary and the layers panel; put the file list underneath. | done in sprint 2 | ## Pass 2. Interaction states: 3/10 No screen specifies anything but the full, happy state. The proposed state table (pending): ``` FEATURE | LOADING | EMPTY | ERROR | PARTIAL ---------------------|-------------------------------|---------------------------------------|-----------------------------------------|------------------------------ Package intake | per-file row "Reading…" | drop zone + "Start with the protocol" | "Not recognised" row, keep going | checklist shows what each gap costs Study record fields | skeleton rows | "No protocol yet" | field marked "Needs review" w/ passage | VI/EN disagreement flagged Profile | — | "No export approved yet" + steward | "Export refused: " from hospital| suppressed rows: "fewer than 10" Clinician review | — | "Nothing awaiting review" | decision without name refused inline | progress "18 of 22 reviewed" Simulate | progress per scenario (secs) | "Write a brief first" | run refused: missing version, shown | fallbacks listed with source Report | — | — | "Export blocked: not signed" | "Unsigned draft" watermark ``` | # | Finding | Recommended fix | State | |---|---|---|---| | 5 | No empty, error or partial states for any screen. A refused export or a missing protocol would show a blank page during a live demo. | Adopt the table above and draw the four refusal states, since they are where trust is won: export refused, field needs review, run refused, export blocked. | pending | | 6 | Suppressed cells have no designed treatment. The built retrospective says "fewer than the minimum cell size". | Use one mark for suppressed values: a dash with the tooltip "fewer than 10 patients, withheld in the hospital", the same everywhere. | pending | ## Pass 3. User journey: 7/10 Storyboard, copied from the accepted PRD §6 storyline: ``` ACT | AUDIENCE DOES | SHOULD FEEL | PLAN SPECIFIES? -------------|--------------------------------|----------------------------------|--------------------------------------- 1 Ingest | watches files drop in | "they can take our mess" | yes (drawn); no loading state (P2 #5) 2 Understand | reads planned vs actual | recognition: "that is our study" | yes; gaps unlabelled on drawn screen 3 Learn | sees values with marks, review | "doctors stay in charge" | review panel drawn, not built (P7) 4 Apply | sees power drop 88 → 73 | the jolt: "our designs are wrong"| drawn yes, built buries it (P1 #3) 5 Trust | replay, calibration, limits | "they tell us what they can't do"| built; not drawn (P7) Close | named person signs the report | "this is a real deliverable" | sign-off drawn as a button only ``` | # | Finding | Recommended fix | State | |---|---|---|---| | 7 | Act 4's jolt depends on the change column (#3). Without it the room sees a table and moves on. | Covered by #3; also add one sentence under the table in plain words, such as "Under local behaviour the same design loses a sixth of its power." | pending | | 8 | The close has no moment. Sign-off is a button on the report. | Make sign-off a short step: the signer's name, role and time, and the export buttons unlocking. Under a minute, and it ends the story on a deliverable. | pending | ## Pass 4. AI slop risk: 7/10 **Mode:** OPERATE. **Hard rejections.** Hit #7, "App UI made of stacked cards instead of layout", on the **built** pages: every section is a bordered card stacked down the page. The drawn screens mostly use a primary table plus a side panel, which is correct. **Litmus** | Check | Answer | Evidence | |---|---|---| | Product clear in the first screen? | Yes | Rail, study name and zone indicator | | One strong visual anchor? | Yes on the drawn screens; no on the built ones | The built pages have no anchor | | Understandable from headlines alone? | Yes | | | Each section has one job? | Mostly | | | Cards necessary? | No on the built pages | | | Motion? | None specified, which is fine | | | Premium without shadows? | Yes | | **Avoided:** gradients, icons in circles, emoji, centred layouts, system-ui. Be Vietnam Pro was chosen for Vietnamese diacritics, and IBM Plex Mono is used for numbers only, so the mono has a job rather than being decoration. | # | Finding | Recommended fix | State | |---|---|---|---| | 9 | The built pages are stacks of cards. | Each screen gets one primary workspace (the main table) and one side panel (source, review or evidence); cards only where the card is the interaction, such as a review item. | pending | ## Pass 5. Design system alignment: 4/10 | # | Finding | Recommended fix | State | |---|---|---|---| | 10 | There is no DESIGN.md. Tokens are listed in the README, but there is no spacing scale, no type scale and no component inventory, so the framework port will re-decide them. | Write DESIGN.md from the README tokens. Add a spacing scale (4, 8, 12, 16, 24, 32), a type scale and the components already in code (LabelMark, Quantity, SourceLink, SampleBanner, Suppressed), with their rules. Or run `/design-consultation` first. | **done in sprint 1** | | 11 | The drawn screens break hard rule 4. Retrospective gaps ("−6%", "+16 pts") and the simulate values have no marks or intervals; the report's evidence table has no interval column. | The accepted P-6 already covers the report. Extend it: every number on every drawn screen gets its mark, including gaps, which take the weakest label of the two values compared. Redraw before the framework port. | pending | ## Pass 6. Responsive and accessibility: 3/10 | # | Finding | Recommended fix | State | |---|---|---|---| | 12 | The demo is shown on a projector to a room, but the design assumes a 1440×900 laptop at reading distance. Captions are 12px, chart labels 11px and body text 14px; numbers in mono at 12px will not read from the back of a room. | Add a presentation mode: body 18px, numbers 20px and up, captions 15px, rail collapsed to act names. Toggle it with one key. Leave the analyst view as is. | pending | | 13 | No keyboard or focus specification. The review queue (confirm, correct, reject) is a keyboard-heavy task for an investigator. | Specify keys for the review queue (C confirm, E correct, R reject, J and K to move), visible focus rings in the accent colour, and landmarks for rail, main and side panel. | pending | | 14 | Minimum width is unspecified. The owner works on a desktop, but a hospital research unit may use smaller screens. | Set 1280px as the minimum supported width, with the side panel collapsing under the table below 1440px. Phones are out of scope. | pending | ## Pass 7. Unresolved design decisions | Decision needed | If deferred, what happens | |---|---| | The four undrawn screens: brief, field review, export approval, de-identification review | Engineers build them as plain forms; act 4 opens on a form, and the steward's approval looks like a checkbox | | Clinician review panel: drawn, but not built (the build scripts the decisions) | Act 3 has nothing for the investigator to do live | | Vietnamese quotes with English translations (drawn on the feedback screen, not built) | Non-Vietnamese buyers cannot read the evidence; the translation must go through the gateway and be labelled machine-translated | | "Ways to recover the timeline" levers on the drawn simulate screen | A strong feature with no PRD feature ID; it overlaps the design critique (F2.5), which is the first cut. Decide whether it is in the demo | | Language switch: per page, or the whole app | Mixed-language screens during the demo | ## NOT in scope - Phone layouts: desktop and projector only. - Dark mode: the use scene is a lit meeting room and an office. - Motion: none is needed beyond progress during simulation. ## What already exists - Tokens in `design/README.md`. - Components in `platform_zone/web/components.py`: label marks drawn as shape plus word, the quantity renderer that refuses a bare number, the sample banner, and the rail. - Six drawn screens with real copy. - Eight built pages that already carry the label rule, the interval column (P-6) and the calibration panel. ## Implementation tasks Synthesized from this review's findings. All are pending owner confirmation. - [ ] **T1 (P1, human: ~1d / CC: ~30min)** — web — Simulate screen on the drawn layout with a "What changes" column - Surfaced by: Pass 1 #3, Pass 3 #7 - Files: `platform_zone/web/static_site.py` (then the framework port) - Verify: the change column is present and each change carries the weakest label of its pair - [ ] **T2 (P1, human: ~2d / CC: ~1h)** — web — five-act rail, and a hospital-zone UI for de-identification review and export approval - Surfaced by: Pass 1 #1, #2 - Files: `platform_zone/web/`, new `hospital_zone/web/` - Verify: no hospital-zone action is reachable from the platform app - [ ] **T3 (P1, human: ~2d / CC: ~1h)** — design — draw the empty, error and partial states and the four undrawn screens - Surfaced by: Pass 2 #5, #6; Pass 7 - Files: `design/screens/` - Verify: every row of the state table has a drawing - [ ] **T4 (P2, human: ~1d / CC: ~30min)** — design — DESIGN.md with scales and components - Surfaced by: Pass 5 #10 - Files: `DESIGN.md` - Verify: the built pages use only DESIGN.md tokens - [ ] **T5 (P1, human: ~1d / CC: ~30min)** — web — presentation mode - Surfaced by: Pass 6 #12 - Files: `platform_zone/web/components.py` - Verify: captions read at 4 m on a projector in a dry run - [ ] **T6 (P2, human: ~1d / CC: ~30min)** — web — review queue keyboard, focus rings, landmarks - Surfaced by: Pass 6 #13 - Files: the review screen - Verify: a full review is done without a mouse - [ ] **T7 (P2, human: ~4h / CC: ~15min)** — web — workspace layout instead of stacked cards - Surfaced by: Pass 4 #9 - Files: `static_site.py` - Verify: one primary table plus a side panel per screen - [ ] **T8 (P2, human: ~4h / CC: ~15min)** — design — marks on every drawn number, including gaps - Surfaced by: Pass 5 #11 - Files: `design/screens/` - Verify: no unmarked number in the drawn screens - [ ] **T9 (P2, human: ~2h / CC: ~10min)** — web — sign-off as a closing step - Surfaced by: Pass 3 #8 - Files: report screen - Verify: export buttons unlock only after the signature ## Completion summary ``` +====================================================================+ | DESIGN PLAN REVIEW — COMPLETION SUMMARY | +====================================================================+ | System Audit | no DESIGN.md; 8 built + 6 drawn screens | | Step 0 | 5/10; all 7 passes reviewed | | Pass 1 (Info Arch) | 5/10 → 5/10 after fixes (4 pending) | | Pass 2 (States) | 3/10 → 3/10 after fixes (2 pending) | | Pass 3 (Journey) | 7/10 → 7/10 after fixes (2 pending) | | Pass 4 (AI Slop) | 7/10 → 7/10 after fixes (1 pending) | | Pass 5 (Design Sys) | 4/10 → 4/10 after fixes (2 pending) | | Pass 6 (Responsive) | 3/10 → 3/10 after fixes (3 pending) | | Pass 7 (Decisions) | 0 resolved, 5 deferred | +--------------------------------------------------------------------+ | NOT in scope | written (3 items) | | What already exists | written | | TODOS.md updates | 0 (tasks go to the sprint plan) | | Approved Mockups | 0 generated (designer needs an OpenAI key) | | Decisions made | 0 added to plan | | Decisions deferred | 19 (14 fixes + 5 open decisions) | | Overall design score | 3/10 → 3/10 | +====================================================================+ ``` Every pass is below 8 because no fix has an owner answer yet. With T1–T5 accepted and done, the lowest pass would rise to about 7. ## Unresolved decisions Fixes #1–#14 above are pending. The five open decisions in Pass 7 are also pending. ## GSTACK REVIEW REPORT | Review | Trigger | Why | Runs | Status | Findings | |--------|---------|-----|------|--------|----------| | CEO Review | `/plan-ceo-review` | Scope & strategy | 1 | DONE_WITH_CONCERNS (not logged) | 6 proposals, 6 accepted, 0 deferred | | Outside Review | Codex via `/plan-eng-review` | Independent 2nd opinion | 1 | unavailable | none | | Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | ISSUES OPEN (PLAN) | 27 issues, 3 critical gaps | | Design Review | `/plan-design-review` | UI/UX gaps | 1 | ISSUES OPEN (FULL) | score: 3/10 → 3/10, 0 decisions | | DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — | - **OUTSIDE COVERAGE:** design outside voices not run (Codex needs a git repository; the owner declined the opt-in question). Eng-phase Codex unavailable. - **VERDICT:** No review CLEAR. eng review required **UNRESOLVED DECISIONS:** - #2 hospital-zone UI for de-identification review and export approval - #3 simulate screen with a "What changes" column - #4 package screen leads with checklist and layers - #5 empty, error and partial states per the state table - #6 one treatment for suppressed values - #7 plain-words sentence under the simulate table - #8 sign-off as a closing step - #9 workspace layout instead of stacked cards - #11 marks on every drawn number, including gaps - #12 presentation mode for projectors - #13 review queue keyboard and focus - #14 minimum width 1280px - Undrawn screens: brief, field review, export approval, de-identification review - Clinician review panel built live, not scripted - Vietnamese quotes with machine-translated English - "Ways to recover the timeline" levers in or out of the demo - Language switch per page or per app + 14 unresolved from prior reviews